[Chapter 31] 31.3 Configuration File Definitions
Author: Bryan Costales & Eric Allman
Date: 1999-01-06T20:10:28Z

#

| Chapter 31 Defined Macros |

## 31.3 Configuration File Definitions

When sendmail reads the configuration file, macros that are declared in that file are assigned values. The configuration-file command that declares macros begins with the letter `D`. There may only be a single macro command per line. The form of the `D` macro configuration command is:

>     DXtext

The symbolic name of the macro (here, `X`) is a single-character or a multicharacter name (see Section 31.4, "Macro Names"):

>     DXtext              single-character name X
>     D{XXX}text          multicharacter name XXX

This must immediately follow the `D` with no intervening space. The value that is given to the macro is the `text`, consisting of all characters beginning with the first character following the name and including all characters up to the end of the line. Any indented lines that follow the definition are joined to that definition. When joined, the newline and indentation characters are retained. Consider the following three configuration lines:

>     DXsometext
>             moretext
>             moretext

>         tabs

These are read and joined by sendmail to form the following `text` value for the macro named `X`:

>     sometext\n\tmoretext\n\tmoretext

The notation `\n` represents a newline character, and the notation `\t` represents a tab character.

If `text` is missing, the value assigned to the macro is that of an empty string; that is, a single byte that has a value of zero.

If both the name and the `text` are missing, the following error is printed, and that `D` configuration line is ignored: [5]

> [5] Prior to V8 sendmail, a macro whose name was missing was given arbitrary garbage as a value. This caused the sendmail program to crash.

>     Name required for macro/class

### 31.3.1 Required Macros (V8.6 and earlier)

Table 31.2 shows the macro names that must (prior to V8.6) be given values in the configuration file.

Table 31.2: Required Macros
Macro |  | Description | As of V8.7
--- | --- | --- | ---
`$e` | Section 34.8.65, SmtpGreetingMessage or $e | The SMTP greeting message | The `SmtpGreetingMessage` option
`$ja` | Section 31.10.20 | Official canonical hostname | Automatically defined all V8
`$l` | Section 34.8.72, UnixFromLine or $l | UNIX From format | The `UnixFromLine` option
`$n` | Section 31.10.26 | Name used for error messages | Automatically defined
`$o` | Section 34.8.45, OperatorChars or $o | Delimiter operator characters | The `OperatorChars` option
`$q` | Section 31.10.30, $q | Format of the sender's address | No longer used

Each of these macros is described at the end of this chapter in Section 31.10. Prior to V8.7, failure to define a required macro could have resulted in unpredictable problems. Beginning with V8.7 sendmail, no macros are required. Some are predefined [6] for you by sendmail, and others have become options.

> [6] But you still may need to declare an occasional macro in your configuration file to solve unusual problems.

### 31.3.2 Syntax of the Configuration File Macro's Text

The `text` of a macro's value in the configuration file may contain escaped control codes. Control codes are embedded by using a backslash escape notation. The backslash escape notations understood by sendmail are listed in Table 31.3.

Table 31.3: Special Characters Allowed in Macro Text
Notation | Placed in Text
--- | ---
`\b` | Backspace character
`\f` | Formfeed character
`\n` | Newline character
`\r` | Carriage-return character
`\\` | Backslash character

All other escaped characters are taken as is. For example, the notation `\X` becomes a `X`, whereas the notation `\b` is converted to a backspace character (usually a CTRL-H). For example,

>     DXO\bc May\, 1996    becomes   O^Hc May, 1996

Here, the `\b` is translated into a backspace (`^H`) character, and the `\,` is translated into a lone comma character.

Note that prior to V8.8, the first comma and all characters following it were stripped from the text unless the comma was quoted or escaped. For example,

>     DXMay, 1996    becomes   May

Beginning with V8.8 sendmail, the comma is no longer special in defined macros.

Quoted `text` will have the quotation marks stripped. Only double quotation marks are recognized. Multiple parts of `text` may be quoted, or text may be quoted entirely.

Trailing spaces are automatically stripped. If you need to keep trailing spaces you need to quote them:

>     DX"1996 "

Leading space characters are retained in `text` whether they are quoted or not. Spaces are harmless provided that the macro is used only in rules (because spaces are token separators); but if the macro is used to define other macros, problems can arise. For example,

>     Dw ourhost
>     DH nlm.nih.gov
>     Dj $w.$H

Here, the `text` of the `$w` and `$H` macros is used to define the `$j` macro. The `$j` macro is used in the HELO SMTP command and in the `Message-ID:` header line. The value given to `$j` by the above is

>        ourhost. nlm.nih.gov

>      two        a space
>      spaces

Here, the value of `$j` should contain a correctly formed, fully qualified domain name. The unwanted spaces cause it to become incorrectly formed, which can cause mail to fail.

31.2 Command-Line Definitions |  | 31.4 Macro Names